AdamWeightDecay
=================

对权重执行 Adam Weight Decay（AdamW）优化更新，原地写回 ``var``、``m``、``v``。

.. math::

    \begin{aligned}
    m_t &= m_{t-1} + (g_t - m_{t-1}) \cdot (1 - \beta_1) \\
    v_t &= v_{t-1} + (g_t^{2} - v_{t-1}) \cdot (1 - \beta_2) \\
    var_t &= var_{t-1} - lr \cdot \left( \frac{m_t}{\sqrt{v_t} + \epsilon} + decay \cdot var_{t-1} \right)
    \end{aligned}

其中 :math:`g_t` 为梯度，:math:`m_t` / :math:`v_t` 为一阶 / 二阶动量，
:math:`decay` 为权重衰减系数。本实现对区间 ``[start, end)`` 内元素逐点更新。

输入：
        - **var** - 待更新权重张量地址（输入/输出，原地更新）
        - **m** - 一阶动量张量地址（输入/输出，原地更新）
        - **v** - 二阶动量张量地址（输入/输出，原地更新）
        - **grad** - 梯度张量地址
        - **float_Parameters** - 浮点超参数组，长度 5，布局见下
        - **int_Parameters** - 整数参数数组，长度 2，布局见下
        - **core_mask** - 核掩码（仅共享存储版本使用）

**float_Parameters 布局：**

        - ``[0]`` ``lr`` - 学习率
        - ``[1]`` ``beta1`` - 一阶动量衰减系数
        - ``[2]`` ``beta2`` - 二阶动量衰减系数
        - ``[3]`` ``epsilon`` - 数值稳定项
        - ``[4]`` ``decay`` - 权重衰减系数

**int_Parameters 布局：**

        - ``[0]`` ``start`` - 参与计算的起始索引（含）
        - ``[1]`` ``end`` - 参与计算的结束索引（不含）

输出：
        - **var** / **m** / **v** - 原地写回更新结果

支持平台：
        ``FT78NE``
        ``MT7004``

.. note::
        - FT78NE 支持 fp32
        - MT7004 支持 fp16、fp32
        - ``hp_`` 版本中 ``float_Parameters`` 元素类型为 ``float16``；``fp_`` 版本为 ``float``

**共享存储版本:**

.. c:function:: void hp_adam_weight_decay_s(float16 *var, float16 *m, float16 *v, float16 *grad, float16 *float_Parameters, int *int_Parameters, int core_mask)
.. c:function:: void fp_adam_weight_decay_s(float *var, float *m, float *v, float *grad, float *float_Parameters, int *int_Parameters, int core_mask)

**C调用示例：**

.. code-block:: c
    :linenos:
    :emphasize-lines: 22

    // MT7004 示例（共享存储多核，DDR 地址）
    void TestAdamWeightDecaySMCFp32(int length, int core_mask) {
        int core_id = get_core_id();
        int logic_core_id = GetLogicCoreId(core_mask, core_id);
        int core_num = GetCoreNum(core_mask);
        float *var = (float *)0x81000000;
        float *m = (float *)0x82000000;
        float *v = (float *)0x83000000;
        float *grad = (float *)0x84000000;
        float *float_Parameters = (float *)0x85000000;
        int *int_Parameters = (int *)0x85000014;
        if (logic_core_id == 0) {
            float_Parameters[0] = 0.001f;  // lr
            float_Parameters[1] = 0.9f;    // beta1
            float_Parameters[2] = 0.999f;  // beta2
            float_Parameters[3] = 1e-4f;   // epsilon
            float_Parameters[4] = 0.01f;   // decay
            int_Parameters[0] = 0;         // start
            int_Parameters[1] = length;   // end
        }
        sys_bar(0, core_num);
        fp_adam_weight_decay_s(var, m, v, grad, float_Parameters, int_Parameters, core_mask);
    }

    void main() {
        int core_mask = 0b1111;
        TestAdamWeightDecaySMCFp32(4096, core_mask);
    }

**私有存储版本:**

.. c:function:: void hp_adam_weight_decay_p(float16 *var, float16 *m, float16 *v, float16 *grad, float16 *float_Parameters, int *int_Parameters)
.. c:function:: void fp_adam_weight_decay_p(float *var, float *m, float *v, float *grad, float *float_Parameters, int *int_Parameters)

**C调用示例：**

.. code-block:: c
    :linenos:
    :emphasize-lines: 16

    // MT7004 示例（私有存储单核，AM 地址）
    void TestAdamWeightDecayAMFp32(int length) {
        float *var = (float *)0x10000000;
        float *m = (float *)0x10020000;
        float *v = (float *)0x10040000;
        float *grad = (float *)0x10060000;
        float *float_Parameters = (float *)0x1007F000;
        int *int_Parameters = (int *)0x1007F014;
        float_Parameters[0] = 0.001f;  // lr
        float_Parameters[1] = 0.9f;    // beta1
        float_Parameters[2] = 0.999f;  // beta2
        float_Parameters[3] = 1e-4f;   // epsilon
        float_Parameters[4] = 0.01f;   // decay
        int_Parameters[0] = 0;         // start
        int_Parameters[1] = length;   // end
        fp_adam_weight_decay_p(var, m, v, grad, float_Parameters, int_Parameters);
    }

    void main() {
        TestAdamWeightDecayAMFp32(2048);
    }